package com.hongji.lms5xxcommunicator.grid.update;

import com.hongji.lms5xxcommunicator.grid.core.RasterState;

/**
 * <p>
 * 更新策略接口：定义如何将一批点（xs/ys/zs）应用到 {@link RasterState} 中。<br/>
 * 不同实现可使用不同的合并逻辑（如均值合并、单点替换等）。
 * </p>
 *
 * <p><b>职责</b></p>
 * <ul>
 *   <li>接收输入点数组（X/Y/Z 三维坐标）。</li>
 *   <li>根据策略更新 {@link RasterState} 的栅格数据。</li>
 *   <li>由具体实现类保证更新逻辑的正确性。</li>
 * </ul>
 *
 * <p><b>用法</b></p>
 * <ol>
 *   <li>在栅格合并时，根据配置选择具体实现类。</li>
 *   <li>调用 {@link #apply(RasterState, double[], double[], double[])} 方法，将点批量写入栅格。</li>
 *   <li>后续体积计算与区域峰值统计依赖于更新后的 {@link RasterState}。</li>
 * </ol>
 *
 * @see RasterState
 * @see MeanUpdateStrategy
 * @see ReplaceSingleElseMeanStrategy
 */
public interface UpdateStrategy {

    /**
     * <p>
     * 将一批点应用到指定 {@link RasterState}。
     * </p>
     *
     * <p><b>约定</b></p>
     * <ul>
     *   <li>输入数组 {@code xs}/{@code ys}/{@code zs} 长度必须一致。</li>
     *   <li>实现类应处理越界点/异常值（可选择跳过）。</li>
     *   <li>方法本身不返回值，修改作用体现在 {@code RasterState} 内部。</li>
     * </ul>
     *
     * @param s 目标栅格状态
     * @param xs 点集的 X 坐标数组
     * @param ys 点集的 Y 坐标数组
     * @param zs 点集的 Z 坐标数组
     */
    void apply(RasterState s, double[] xs, double[] ys, double[] zs);

}
